<?xml version="1.0" encoding="UTF-8"?>
<!--

       Copyright 2006-2019 the original author or authors.

       Licensed under the Apache License, Version 2.0 (the "License");
       you may not use this file except in compliance with the License.
       You may obtain a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

       Unless required by applicable law or agreed to in writing, software
       distributed under the License is distributed on an "AS IS" BASIS,
       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
       See the License for the specific language governing permissions and
       limitations under the License.

-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>MyBatis Dynamic SQL V1 Usage Notes</title>
  <link rel="stylesheet" type="text/css" href="../mbgstyle.css" />
</head>
<body>
<h1>MyBatis Dynamic SQL V1 Usage Notes</h1>
<p><b>This runtime is deprecated and will be removed in a future version. Please switch the the MyBatis Dynamic SQL V2
runtime!</b></p>

<p>This page is a short introduction to using the classes generated for the MyBatis3DynamicSQLV1 runtime.  These classes
are dependent on the <a href="http://www.mybatis.org/mybatis-dynamic-sql/docs/introduction.html">MyBatis Dynamic SQL</a>
library.  Please refer to that site for full information about how the library works.</p>

<p>For each introspected table, the generator will generate three objects:</p>
<ol>
  <li>A "record" class that represents a row in the table.  This is the same as other runtimes</li>
  <li>A "support" class that includes a table definition and column definitions for the database table</li>
  <li>A mapper interface with all the typical methods generated by the other runtimes.</li>
</ol>

<p>Important notes about the generated objects:</p>
<ul>
  <li>No XML is generated</li>
  <li>No separate "Example" class is generated</li>
  <li>There are no separate "with BLOBs" and "without BLOBs" methods.  If your table includes BLOB fields, then
      they are included in all operations.</li>
  <li>Model classes are always generated in the "flat" model meaning there is no separate primary key class or BLOBs class</li>
  <li>Java 8 or higher is required</li>
  <li>MyBatis 3.4.2 or higher is required</li>
</ul>

<h2>Format of the "Support" classes</h2>
<p>A "support" class is created for each table.  The support class includes a definition of the table and all the columns
in the table.  These items are used as input to the code generated in the mappers - most often for the where clauses you
will write.</p>

<p>For example, suppose there is a table "TABLE_CODE" in schema "MYSCHEMA".  Further suppose that table has "ID" and
"DESCRIPTION" columns.  The generated support class will look like this: </p>

<pre>
package example;

import java.sql.JDBCType;
import org.mybatis.dynamic.sql.SqlColumn;
import org.mybatis.dynamic.sql.SqlTable;

public final class TableCodeDynamicSqlSupport {
    public static final TableCode tableCode = new TableCode();
    public static final SqlColumn&lt;Integer&gt; id = tableCode.id;
    public static final SqlColumn&lt;String&gt; description = tableCode.description;

    public static final class TableCode extends SqlTable {
        public final SqlColumn&lt;Integer&gt; id = column("ID", JDBCType.INTEGER);
        public final SqlColumn&lt;String&gt; description = column("DESCRIPTION", JDBCType.VARCHAR);

        public TableCode() {
            super("MYSCHEMA.TABLE_CODE");
        }
    }
}
</pre>

<p>In your code, it is typical to import the static elements of this support class so they can be used directly in the
code you write.  With this static import you can refer to the fields
in either a direct or qualified manner - "id" or "tableCode.id".</p>

<h2>Usage of the Mapper Classes</h2>
<p>The following methods work the same as the other runtimes and we won't cover them here:</p>
<ul>
  <li>Delete by Primary Key</li>
  <li>Insert - will insert nulls</li>
  <li>insert selective - ignores null properties</li>
  <li>Select by Primary Key</li>
  <li>Update by Primary Key - will set null values</li>
  <li>Update by Primary Key Selective - ignores null values</li>
</ul>

<p>The "by example" methods work very differently.  The generator will create the following "by example" methods:</p>
<ul>
  <li>Count by example</li>
  <li>Delete by example</li>
  <li>Select by example</li>
  <li>Update by example</li>
</ul>

<p>Each of these methods includes support for a very flexible WHERE clause. Each method returns a builder object that requires you
to optionally add a WHERE clause, then complete the builder and execute the method.  If you don't supply a WHERE clause the statement
will still work - but it will apply to all rows of a table.  All builders are completed by calling the <code>build</code> method
and finally the statement is executed by calling the the <code>execute</code> method.</p>

<p>For example, you can retrieve the total number of rows in a table by calling the count by example method without a WHERE clause.
That code looks like this:</p>

<pre>
  long totalRows = mapper.countByExample()
          .build()
          .execute();
</pre>

<p>You can retrieve all rows in a table by calling select by example without a WHERE clause like this:</p>

<pre>
  List&lt;TableCode&gt; allRecords = mapper.selectByExample()
          .build()
          .execute();
</pre>

<p>It is far more interesting to add WHERE clauses to these methods.  To add support for WHERE clauses, you should import the static
elements from the support class as shown above, and you should also import the SqlBuilder support.  Then you can code arbitrarily
complex where clauses, and "ORDER BY" phrases as shown below:</p>

<pre>
import static example.TableCodeDynamicSqlSupport.*;  // import the generated "support" items
import static org.mybatis.dynamic.sql.SqlBuilder.*;  // import MyBatis Dynamic SQL where support

public class SomeService {

    public void simpleWhere {
        ...
        // Simple WHERE clause
        List&lt;TableCode&gt; records = mapper.selectByExample()
                .where(id, isEqualTo(3))
                .build()
                .execute();        
        ...
    }

    public void complexWhere1 {
        ...
        // Simple WHERE clause with OR
        List&lt;TableCode&gt; records = mapper.selectByExample()
                .where(id, isEqualTo(3))
                .or(description, isLike("f%"))
                .build()
                .execute();        
        ...
    }

    public void complexWhere2 {
        ...
        // complex WHERE and ORDER BY
        List&lt;TableCode&gt; records = mapper.selectByExample()
                .where(id, isLessThan(10), and(description, isEqualTo("foo")))
                .or(description, isLike("b%"))
                .orderBy(id.descending())
                .build()
                .execute();        
        ...
    }
}
</pre>

<p>The "by example" methods in this runtime are far more flexible then the "by example" methods in the other runtimes.
Please the documentation for <a href="http://www.mybatis.org/mybatis-dynamic-sql/docs/introduction.html">MyBatis Dynamic SQL</a>
to learn more about the options available.</p>

</body>
</html>
